TreeGrid Cells Tutorial
5. Permissions and input validation
Editing and other permissions and validation during editing, before save and before upload
-
Permissions
All capabilities are permitted by default if they don't collide with other settings.
Permission settings are processed in this order:
grid, cell, cell of default row, row, default row, column, default column.
If any of the attribute has not empty value, processing ends and the value is used.
-
For whole grid you can prohibit capability in
<Cfg> tag:
all cells
Editing,
all cells or rows
Pasting,
all rows
Deleting,
Selecting,
Adding,
Sorting,
Dragging,
all columns
ColMoving,
ColResizing.
-
For cell you can use:
the cell
CanEdit,
CanFocus,
CanPaste.
Not focused cell cannot be edited.
-
For row you can use:
all cells
CanEdit,
CanFocus,
CanCopyPaste,
the row
CanDelete,
CanSelect,
CanDrag,
CanFilter.
-
For column you can use:
all cells
CanEdit,
CanFocus,
CanCopyPaste,
the column
CanResize,
CanMove,
CanFilter,
CanSort,
CanHide.
The CanEdit permission does not affect cell side Button and Icon,
to hide cell side Button or Icon, you must clear it explicitly by ...Button="" or ...Icon="".
The Editing permission does not affect Space and Filter rows,
editing permissions in Space and Filter row must be controlled individually by CanEdit attribute.
The individual actions for many capabilities are defined in <Actions> tag, predefined in Defaults.xml.
And the behavior can be changed by assigning different action to the event.
For example there is set <Action OnDel="DeleteRowF OR UndeleteRowF,1"/> to delete row by pressing Del key.
You can set <Actions OnDel=""/> to disable this behavior or assign to OnDel different action(s).
-
Calculated permissions
All row and cell permissions can be calculated according to some condition, for example cell (checkbox) value.
Just set such formula (e.g. CanEditFormula), set the row as Calculated and add the attribute name to CalcOrder.
For example <I CanDeleteFormula='Col3' Col1CanEditFormula='Col2>10' Calculated='1' CalcOrder='Col1CanEdit,CanDelete' />.
-
Changing
permissions
by API
All the permissions, like many other attributes, can be changed by API.
Change the <Cfg/> attributes by direct assignment to TGrid object, like Grid.Editing=0.
Remember, to bool or integer attributes always set numbers like Grid.Deleting=0 and never strings like Grid.Deleting="0".
After changing the global attribute, it is often needed to repaint the grid or body by RefreshBody or Refresh.
For setting row, column or cell attribute use SetAttribute method, to show the changes, set its refresh parameter.
You can also calculate some permissions dynamically by JavaScript API events
OnCanEdit,
OnCanRowAdd,
OnCanRowDelete,
OnCanDrop.
-
Size
attribute is the simplest mask, it limits input to the specified count of characters.
-
Cell
Type
can be set to Int, Float or Date.
These types permit to input only characters acceptable for given type or its format.
The input character mask of the Type can be overridden by EditMask attribute, see below.
-
EditMask
checks and validates input during editing.
The EditMask is RegExp expression that is applied after every key press while editing the cell. When it fails, the key is ignored.
The EditMask can be used to specify the permitted characters or to specify base structure of the requested input data.
It should not be too restrictive to not bother users while editing.
When the EditMask fails and refuses the key, it shortly blinks the cell by background color set by MaskColor.
-
ResultMask
checks and validates input before saving to the cell value.
The ResultMask is RegExp expression that is applied after a user presses Enter or accepts the input by any other method.
If the ResultMask fails, it does not accept the input and continues editing. The editing can be always ended by canceling it by Esc key.
If the ResultMask fails and ResultText is set, it alerts this message and continues editing.
It also calls OnResultMask to provide custom handler for the error.
The edited value can be also checked, validated and modified by API in events OnEndEdit (to continue editing on error), OnValueChanged (to modify the value), OnAfterValueChanged (to do something after change).
-
Validate
attribute controls data validation before uploading changes to server.
If the Validate is set and changes are going to be uploaded to server, it iterates all ResultsMask in grid and checks if all data are correct.
The Validate can be set to iterate all rows (for example to ensure that no required cell is empty) or only added rows.
When Validate finds errors, it can mark them as Error with red background and / or focus and start editing the first error cell.
It can also show alert message or confirm message to let a user to upload the incorrect data anyway.
It also calls API event OnValidateError for custom handling.
The validation can be run also by Action Validate.